home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / nihcl-30.lha / nihcl-3.0 / INSTALL < prev    next >
Text File  |  1990-05-25  |  15KB  |  529 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.        Installation   NIH Class Library Revision 3.0   Installation
  8.  
  9.  
  10.  
  11.             INTRODUCTION
  12.  
  13.             This is the Installation  Guide  for  the  NIH  Class  Library
  14.             (previously known as the "OOPS" Class Library) Revision 3.0.
  15.  
  16.             The NIH Class Library is intended to be  portable  to  a  UNIX
  17.             system compatible with either System V or 4.2/4.3BSD and which
  18.             supports the AT&T C++ translator Release 2.00, Release 2.1, or
  19.             other compatible C++ compiler.  We have ported and tested this
  20.             library on the following systems:
  21.  
  22.                  Sun-3 with SunOS 3.5
  23.                  Sun-3 with SunOS 4.0
  24.                  Sun-4 with SunOS 4.0
  25.  
  26.             Send comments to:
  27.  
  28.                  Keith Gorlen
  29.                  Building 12A, Room 2033
  30.                  Computer Systems Laboratory
  31.                  Division of Computer Research and Technology
  32.                  National Institutes of Health
  33.                  Bethesda, MD 20892
  34.  
  35.                  phone: (301) 496-1111
  36.                  Internet : kgorlen@alw.nih.gov
  37.                  uucp: uunet!nih-csl!kgorlen
  38.  
  39.  
  40.             GUIDE TO THIS DISTRIBUTION KIT
  41.  
  42.  
  43.             The NIH Class Library distribution  kit  consists  of  a  main
  44.             directory and the following subdirectories:
  45.  
  46.                  errfac     Error Message Facility source files
  47.                  lib         Source  files  for  the  basic   library
  48.                  classes
  49.                  test       Test suite for the basic library classes
  50.                  vector     Source files for the Vector classes
  51.                  vectest    Test suite for the Vector classes
  52.                  ex         Example programs for the book
  53.  
  54.             The main directory is refered to as  NIHCL  in  the  following
  55.             discussion, but may be placed anywhere.
  56.  
  57.             Most subdirectories have files named  MAKEFILE  and  Makefile.
  58.             The MAKEFILE is used by the installation procedure, and should
  59.             work with both the System  V  and  BSD  version  of  the  make
  60.             utility.   The  fancier  Makefile is used for development, and
  61.  
  62.  
  63.  
  64.             May 25, 1990                                          Page 1
  65.  
  66.  
  67.  
  68.  
  69.  
  70.             Installation   NIH Class Library Revision 3.0   Installation
  71.  
  72.  
  73.             may not work under BSD.
  74.  
  75.  
  76.  
  77.             SUMMARY OF STEPS IN INSTALLING THE NIH CLASS LIBRARY
  78.  
  79.                 1.      Update C++ system library and include files
  80.                 2.      Edit NIHCL/Makefile
  81.                 3.      Edit NIHCL/lib/nihclconfig.h
  82.                 4.      Build and install error message facility*
  83.                 5.      Build NIHCL basic  classes,  Vector  classes,  and
  84.                       test suite
  85.                 6.      Test basic classes and Vector classes
  86.                 7.      Build NIHCL basic  classes,  Vector  classes,  and
  87.                       test suite with multiple inheritance support
  88.                 8.      Test  basic  classes  and  Vector   classes   with
  89.                       multiple inheritance support
  90.                 9.      Install class libraries*
  91.                 10.     Build example programs
  92.                 11.     Test example programs
  93.  
  94.             * root permission may be required
  95.  
  96.  
  97.  
  98.  
  99.             INSTALLING THE NIH CLASS LIBRARY
  100.  
  101.             1. Update C++ system library and include files
  102.  
  103.             No updates to R2.00 of the AT&T C++ Translator  are  required.
  104.             However,  if  you  are using R2.1, be sure to make the changes
  105.             documented in the section COMPILING UNDER AT&T C++  TRANSLATOR
  106.             RELEASE 2.1 in the NIH Class Library Release Notes.
  107.  
  108.             2. Edit NIHCL/Makefile
  109.  
  110.             Edit NIHCL/Makefile to change make  variables  as  needed  for
  111.             your  environment.   Here  are  the  settings shipped with the
  112.             distribution kit:
  113.  
  114.                  # C++ compiler
  115.                  CC = CC
  116.  
  117.                  # C++ debug switch
  118.                  CCDEBUG =
  119.                  #CCDEBUG = -g
  120.  
  121.                  # C++ flags
  122.                  # NOTE: Disable +p option when compiling with AT&T R2.1
  123.                  #CCFLAGS = +p
  124.                  #CCFLAGS =
  125.  
  126.                  # C++ include files
  127.  
  128.  
  129.  
  130.             Page 2                                          May 25, 1990
  131.  
  132.  
  133.  
  134.  
  135.  
  136.             Installation   NIH Class Library Revision 3.0   Installation
  137.  
  138.  
  139.                  I = /usr/include/CC
  140.  
  141.                  # If using BSD
  142.                  SYS = BSD
  143.                  # If using System V
  144.                  #SYS = SYSV
  145.  
  146.                  # Compile with nested types
  147.                  # (works with AT&T R2.1 and GNU C++)
  148.                  NESTED_TYPES =
  149.                  #NESTED_TYPES = -DNESTED_TYPES
  150.  
  151.                  # Disable AT&T R2.0/R2.1 bug work-around code
  152.                  BUGDEFS =
  153.                  #BUGDEFS = -DBUG_bC2728 -DBUG_38 -DBUG_39
  154.                  -DBUG_OPTYPECONST
  155.                  # Defining BUG_TOOBIG disables code that
  156.                  # prevents C compiler "yacc stack overflows" error
  157.                  #BUGDEFS = -DBUG_bC2728 -DBUG_38 -DBUG_39
  158.                  -DBUG_OPTYPECONST -DBUG_TOOBIG
  159.  
  160.                  # Enable debug code
  161.                  DEBUGDEFS =
  162.                  #DEBUGDEFS = -DDEBUG_OBJIO -DDEBUG_PROCESS
  163.  
  164.                  # Flags for ln
  165.                  #LNFLAGS =
  166.                  LNFLAGS = -s
  167.  
  168.                  # If using "patch"
  169.                  MAIN = _main.c_p
  170.                  # If using "munch"
  171.                  #MAIN = _main.c_m
  172.  
  173.                  # Target library for installation of Error Facility
  174.                  LIB_ID = libC
  175.  
  176.                  # Target Directories for Installation
  177.  
  178.                  # directory for libnihcl.a
  179.                  NIHCLLIBDIR = /usr/local/lib
  180.                  # directory for NIHCL include files
  181.                  NIHCLINCDIR = /usr/include/nihcl
  182.                  # directory where ${LIB_ID}.a resides
  183.                  CLIBDIR = /usr/local/lib/C++R2.0
  184.                  # directory for errgen utility
  185.                  ERRGENDIR = /usr/local/bin
  186.                  # directory for errgen table file
  187.                  ERRTABDIR = /usr/local/lib
  188.                  # directory for errlib.h and errors.h
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.             May 25, 1990                                          Page 3
  197.  
  198.  
  199.  
  200.  
  201.  
  202.             Installation   NIH Class Library Revision 3.0   Installation
  203.  
  204.  
  205.                  ERRINCDIR = $I
  206.  
  207.  
  208.             3. Edit NIHCL/lib files
  209.  
  210.             3.1 Edit nihclconfig.h
  211.  
  212.             The NIH Class Library source is configured for your system  by
  213.             setting  flags  in  NIHCL/lib/nihclconfig.h  which specify the
  214.             machine model and operating system (UNIX variant).
  215.  
  216.             To configure the NIH Class Library for  one  of  the  not  yet
  217.             implemented  options, at least all of the parameters appearing
  218.             in nihclconfig.h will have to be defined for that option.
  219.  
  220.             The NIH Class Library should  configure  itself  automatically
  221.             for the following machines:
  222.  
  223.                  sun/mc68000
  224.                  sun/sparc
  225.  
  226.             Classes Process, HeapProc,  StackProc,  Scheduler,  Semaphore,
  227.             and  SharedQueue  have  some machine-specific dependencies and
  228.             will not work  unless  the  SETJMP()/LONGJMP()  functions  are
  229.             properly defined.  See the NIH Class Library Release Notes for
  230.             directions on porting the Process classes.
  231.  
  232.             3.2 Edit Object.h
  233.  
  234.             The file Object.h defines three  versions  of  a  preprocessor
  235.             macro  named  STRINGIZE,  which  forms  some  symbol  names by
  236.             concatenating the class name argument with other strings. Each
  237.             version  does  this a different way.  The version for use with
  238.             ANSI C preprocessors, conditionalized on the symbol  __STDC__,
  239.             uses  ##  for  concatenation.   If you are not using an ANSI C
  240.             preprocessor, defining the symbol BS_NL  in  Object.h  selects
  241.             the   version   that  uses  the  sequence  \<newline>  as  the
  242.             concatenation separator, which seems to work with most  System
  243.             V  UNIX  systems.   If  you  do  not define BS_NL, you get the
  244.             version of DEFINE_CLASS that uses an  empty  comment  sequence
  245.             (/**/), which works with most Berkeley UNIX systems.
  246.  
  247.             Object.h should require no editing on most systems.
  248.  
  249.             4. Install error message facility
  250.  
  251.             (Skip this step for MASSCOMP/RTU)
  252.  
  253.                  su      (if installing in protected directory)
  254.                  make errorfacility
  255.  
  256.             This builds an error  message  registery  facility  and  error
  257.             processing  library  similar  to  errcom  and  the  3E library
  258.             routines on the MASSCOMP.
  259.  
  260.  
  261.  
  262.             Page 4                                          May 25, 1990
  263.  
  264.  
  265.  
  266.  
  267.  
  268.             Installation   NIH Class Library Revision 3.0   Installation
  269.  
  270.  
  271.             The errgen program reads a .err file to determine  a  facility
  272.             name,  and  then  reads  the  file  ${ERRTABDIR}/errgen_tab to
  273.             lookup the number assigned to  that  facility.   The  facility
  274.             number  determines  the  high-order  bits of the error numbers
  275.             which errgen assigns, assuring  that  error  numbers  used  by
  276.             different  libraries  do  not  coincide.  Errgen produces a .h
  277.             file containing error symbols and their assigned numbers,  and
  278.             a  .c file containing a table of error messages and formatting
  279.             information.
  280.  
  281.             This step creates  a  module  containing  the  error  handling
  282.             library    routines    named   errors.o   and   adds   it   to
  283.             ${CLIBDIR}/${LIB_ID}.a, and it copies the files  errlib.h  and
  284.             errors.h into the directory ${ERRINCDIR}.
  285.  
  286.             The test program testerr on  NIHCL/errfac  verifies  that  the
  287.             error  facilities  have  been built correctly.  It returns the
  288.             first and last error defined in the file testerrs.err.
  289.  
  290.  
  291.             5. Build the NIH Class Library, Vector classes, and test suite
  292.  
  293.                  make
  294.  
  295.  
  296.             6. Test the NIH Class Library
  297.  
  298.                  make verify
  299.  
  300.             This runs the test suite and compares the output of each  test
  301.             program  with the contents of a .v file containing the correct
  302.             output.  If the program runs correctly, you'll see the message
  303.             "No  differences  encountered".   Some  tests  such  as  date,
  304.             identdict, process, random, stack, and tim produce  output  to
  305.             the   terminal.    date   outputs  yesterday's,  today's,  and
  306.             tomorrow's date.   identdict  dumps  an  identity  dictionary.
  307.             random  prints out a list of random numbers.  stack prints out
  308.             a CLTNEMPTY error message to test  error  reporting,  and  tim
  309.             prints out the current date and time.
  310.  
  311.             The error test program frequently fails to compare because its
  312.             output   depends   upon  memory  addresses  that  change  from
  313.             implementation to implementation.  error should differ only in
  314.             the object address printed in the CLTNEMPTY error message.
  315.  
  316.             The output  of  fdset  depends  upon  the  maximum  number  of
  317.             allowable  file  descriptors  on your system.  The test output
  318.             was generated under SunOS 4.0, which has a limit  of  64  file
  319.             descriptors.
  320.  
  321.             Several tests that print floating point numbers  may  fail  to
  322.             compare due to formatting differences.
  323.  
  324.             The byte size of the object printed  by  ex8-1  may  vary  for
  325.  
  326.  
  327.  
  328.             May 25, 1990                                          Page 5
  329.  
  330.  
  331.  
  332.  
  333.  
  334.             Installation   NIH Class Library Revision 3.0   Installation
  335.  
  336.  
  337.             different systems.  The test output was produced by a Sun-3.
  338.  
  339.  
  340.             7. Build the NIH Class Library, Vector classes, and test suite
  341.             with multiple inheritance support
  342.  
  343.                  make cleantest
  344.                  make mi
  345.  
  346.  
  347.             8. Test the NIH Class Library, Vector classes, and test suite
  348.             with multiple inheritance support
  349.  
  350.                  make verify
  351.  
  352.             This runs the same tests as in Step 6, with similar results.
  353.  
  354.  
  355.             9. Install the NIH Class Libraries
  356.  
  357.                  su      (if installing in protected directory)
  358.                  make install
  359.  
  360.             The  NIH  Class  Library  archives  libnihcl.a,  libnihclmi.a,
  361.             libnihclvec.a,    and    libnihclvecmi.a    are    copied   to
  362.             ${NIHCLLIBDIR} and ranlib is executed on the  libraries.   All
  363.             header  files  for  basic  classes  are  copied  to  directory
  364.             ${NIHCLINCDIR}.
  365.  
  366.  
  367.             10. Build example programs
  368.  
  369.                  make examples
  370.  
  371.  
  372.             11. Test example programs
  373.  
  374.                  make exverify
  375.  
  376.  
  377.  
  378.             TROUBLE SHOOTING
  379.  
  380.             YACC stack overflows
  381.  
  382.             Some test programs may fail to compile because  they  are  too
  383.             complicated  for  your  C  compiler  and  get  a  "yacc  stack
  384.             overflow".  Either increase the table space in your C compiler
  385.             or  simplify  the  program  by  breaking  it  up into separate
  386.             functions.  The inline  copy  constructors  that  Release  2.0
  387.             automatically  generates  are  frequently  the  source of this
  388.             error.   Explicitly  defining  non-inline  copy   constructors
  389.             solves  the  problem.   See  the  Release  Notes  for  further
  390.  
  391.  
  392.  
  393.  
  394.             Page 6                                          May 25, 1990
  395.  
  396.  
  397.  
  398.  
  399.  
  400.             Installation   NIH Class Library Revision 3.0   Installation
  401.  
  402.  
  403.             details.
  404.  
  405.             Problems with class Exception
  406.  
  407.             Test programs error and except test class Exception,  the  the
  408.             NIH Class Library exception handler. If these programs fail to
  409.             perform correctly suspicion can be directed to the performance
  410.             of system functions setjmp() and longjmp().
  411.  
  412.             Problems with Process classes
  413.  
  414.             Progams process and stackproc test the NIH Class  Library  co-
  415.             routine  mechanism  (classes Process, HeapProc, StackProc, and
  416.             Scheduler), the object queue (class SharedQueue) and semaphore
  417.             (class  Semaphore).   These  are machine-dependent and rely on
  418.             the presence of alloca(), which all systems  do  not  provide,
  419.             and     on    setjmp()/longjmp()    being    implemented    by
  420.             saving/restoring all machine registers, which  is  not  always
  421.             the  case for all systems either.  If the process or stackproc
  422.             tests fail to compile,  link,  or  run,  check  your  system's
  423.             implementations of alloca() setjmp(), and longjmp() -- you may
  424.             need to implement your own versions.
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.             May 25, 1990                                          Page 7
  461.  
  462.  
  463.  
  464.  
  465.  
  466.             Installation   NIH Class Library Revision 3.0   Installation
  467.  
  468.  
  469.             rsi
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.             Page 8                                          May 25, 1990
  527.  
  528.  
  529.